home *** CD-ROM | disk | FTP | other *** search
/ Dr. Windows 3 / dr win3.zip / dr win3 / VISUALBA / PBCWIN.ZIP / PBCWIN.DOC < prev    next >
Text File  |  1993-01-22  |  34KB  |  1,130 lines
  1.                  The PBClone Windows Library
  2.                =-----------------------------=
  3.                          Version 1.0
  4.  
  5.        PBCwin  Copyright (c) 1993  Thomas G. Hanlin III
  6.  
  7.  
  8.  
  9. This is PBCwin, a general-purpose library of 79 routines for
  10. use with Visual Basic for Windows.  The PBCwin collection is
  11. copyrighted and may be distributed only under the following
  12. conditions:
  13.  
  14.    All PBCwin files must be distributed together as a unit.
  15.    No files may be altered, added, or deleted from this unit.
  16.  
  17. You use this library at your own risk.  It has been tested by
  18. me on my own computer, but I will not assume any responsibility
  19. for any problems which PBCwin may cause you.  If you do run
  20. into a problem, please let me know about it, and I will do my
  21. best to verify and repair it.
  22.  
  23. It is expected that if you find PBCwin useful, you will
  24. register your copy.  You may not use PBCwin routines in
  25. programs intended for sale unless you have registered.
  26.  
  27. Registration gives you the right to distribute the PBCWIN.DLL
  28. library with your programs.  It also gets you the latest
  29. version of PBCwin, complete with full source code (written in
  30. Microsoft C 7.0).
  31.  
  32. The PBCwin library can be used with any Windows language that
  33. can access DLLs.  It is currently documented only for VB/Win,
  34. however.  I expect to extend the documentation to cover other
  35. languages in future versions.  PBCwin will be expanding greatly
  36. over the course of the next year or so, as I get a better grip
  37. on the idiosyncracies of Windows programming.
  38.  
  39. If you're familiar with DOS libraries, you'll have no trouble
  40. at all with Windows libraries.  There's one important thing to
  41. keep in mind, however.  DOS libraries are almost always linked
  42. into your .EXE program and become an integral part of it.
  43. Windows libraries are separate from your program and must be
  44. available to Windows when your program is run.  This allows
  45. multiple programs to share the same library code for greater
  46. memory efficiency.  It also means you will need to distribute
  47. the PBCWIN.DLL file with your programs that use it (legal only
  48. for registered PBCwin owners), or simply tell people where they
  49. can get a copy of PBCwin to use with your program.
  50.  
  51. In order to use any of the PBCwin routines in a VB/Win program,
  52. you must place the appropriate declarations in the globals
  53. section of the program.  These declarations can be taken
  54. individually or en masse from the PBCWIN.BI text file.
  55.  
  56. The PBCwinVer function will let you make sure that the version
  57. of PBCWIN.DLL that is being used is, in fact, sufficiently
  58. current as to support the routines your program requires.
  59.  
  60. Name  : BinI                 (Binary Integer)
  61.  
  62. This function converts a binary value, passed to it as a
  63. string, to an integer.  It stops the conversion on reaching the
  64. end of the string or at the first character that is not a valid
  65. binary digit ("0" or "1").
  66.  
  67. See also BinL, which returns a long integer value.
  68.  
  69.    Result% = BinI(St$)
  70.  
  71. St$       binary number, in string form
  72. -------
  73. Result%   integer equivalent of binary number
  74.  
  75. Name  : BinL                 (Binary Long)
  76.  
  77. This function converts a binary value, passed to it as a
  78. string, to a long integer.  It stops the conversion on reaching
  79. the end of the string or at the first character that is not a
  80. valid binary digit ("0" or "1").
  81.  
  82. See also BinI, which returns an integer value.
  83.  
  84.    Result& = BinL(St$)
  85.  
  86. St$       binary number, in string form
  87. -------
  88. Result&   long integer equivalent of binary number
  89.  
  90. Name  : Bytes2Int            (Bytes to Integer)
  91.  
  92. This function combines two bytes, contained in separate
  93. integers, into a single integer value.
  94.  
  95. See also HiByte and LoByte, which may be used to reverse the
  96. process, splitting an integer into two bytes.
  97.  
  98.    Result% = Bytes2Int(Lo%, Hi%)
  99.  
  100. Lo%       low, or least significant, byte
  101. Hi%       high, or most significant, byte
  102. -------
  103. Result%   result of combining bytes into an integer
  104.  
  105. Name  : Checksum             (Checksum)
  106.  
  107. This function calculates an 8-bit checksum for a string.  The
  108. result is compatible with Xmodem and Ymodem file transfer
  109. protocols, and can be used as a fast and simple check of data
  110. validity.  For more rigorous testing, see CRC16.
  111.  
  112.    Result% = Checksum(St$, Bytes%)
  113.  
  114. St$       string for which to calculate checksum
  115. Bytes%    number of characters for which to calculate checksum
  116. -------
  117. Result%   checksum of specified part of string
  118.  
  119. Name  : ComPorts             (Comm Ports)
  120.  
  121. This function returns the number of communications (serial)
  122. ports installed.
  123.  
  124.    Result% = ComPorts()
  125.  
  126. -------
  127. Result%   comm ports (0-3)
  128.  
  129. Name  : CRC16                (CRC, 16-bit)
  130.  
  131. This function calculates a 16-bit "cyclical redundancy check"
  132. checksum, or CRC, for a string.  The result is compatible with
  133. Xmodem and Ymodem file transfer protocols, and can be used as a
  134. check of data validity.
  135.  
  136. Note that the Xmodem and Ymodem file transfer protocols use a
  137. different byte ordering method than typical of Intel machines.
  138. If you intend to use this function in writing file transfer
  139. protocols, you will need to reverse the byte order to MSB
  140. first, LSB second.  This can be accomplished with either
  141. LRotateI or RRotateI with a shift count of 8 (eight), or by
  142. splitting the integer into bytes with LoByte and HiByte, and
  143. swapping the results.
  144.  
  145.    Result% = CRC16(St$, Bytes%)
  146.  
  147. St$       string for which to calculate CRC
  148. Bytes%    number of characters for which to calculate CRC
  149. -------
  150. Result%   CRC of specified part of string
  151.  
  152. Name  : DateSq               (Date Squeeze)
  153.  
  154. This function compresses a date into a single integer.  This
  155. provides a very efficient storage format for dates ranging from
  156. January 1, 1900 to December 31, 2028.
  157.  
  158. Uncompression is done with DayUnsq, MonthUnsq, and YearUnsq.
  159. See also TimeSq, which allows you to compress a time value
  160. similarly.
  161.  
  162. Note that compressed dates are not in a format that may be
  163. readily used for comparison or date math purposes.  If you need
  164. such capabilities, convert the date to a BASIC time/date serial
  165. number first-- see your BASIC manual for details.
  166.  
  167. If you pass a year of 0-99, it will be translated to 1900-1999
  168. before the compression is done.  Depending on your application,
  169. you may wish to assume 0-28 is the same as 2000-2028 instead.
  170. If so, make sure you do an explicit conversion before this
  171. function is called.
  172.  
  173.    Result% = DateSq(MonthNr%, DayNr%, YearNr%)
  174.  
  175. MonthNr%    month number (1-12)
  176. DayNr%      day number (1-31)
  177. YearNr%     year number (1900-2028)
  178. -------
  179. Result%     compressed date
  180.  
  181. Name  : DayUnsq              (Day Unsqueeze)
  182.  
  183. This function returns the day from a compressed date.  It works
  184. in conjunction with the DateSq date compression function.
  185.  
  186.    DayNr% = DayUnsq(Number%)
  187.  
  188. Number%     compressed date
  189. -------
  190. DayNr%      day number
  191.  
  192. Name  : Floppies             (Floppies)
  193.  
  194. This function returns the number of floppy disk drives
  195. installed, up to two.  Although it is possible to have up to
  196. four floppy drives, the PC was designed to expect a maximum of
  197. two, and this routine can't tell if there are more than that.
  198.  
  199.    Result% = Floppies()
  200.  
  201. -------
  202. Result%   floppy drives (0-2)
  203.  
  204. Name  : GetComAddr           (Get Comm Address)
  205.  
  206. This function returns the I/O base port address for a specified
  207. communications (serial) port.  If there is no such serial port,
  208. or if the port is in use, a zero will be returned.
  209.  
  210.    Address% = GetComAddr(PortNr%)
  211.  
  212. PortNr%     communications port number (0-3)
  213. -------
  214. Address%    I/O base port address for comm port
  215.  
  216. Name  : GetPrtAddr           (Get Prt Address)
  217.  
  218. This function returns the I/O base port address for a specified
  219. printer (parallel) port.  If there is no such parallel port, a
  220. zero will be returned.
  221.  
  222.    Address% = GetPrtAddr(PortNr%)
  223.  
  224. PortNr%     printer port number (0-3)
  225. -------
  226. Address%    I/O base port address for printer port
  227.  
  228. Name  : GetTick              (Get clock Tick)
  229.  
  230. This function returns the current system time count.  The count
  231. is the amount of time after midnight, in (approximately) 1/18